Skip to main content

Cache Control

Cache control in REST API design refers to how a server communicates caching policies to clients and intermediaries (like browsers, proxies, and CDNs) using HTTP headers. Proper cache control helps improve performance, reduce server load, and provide a better user experience by avoiding unnecessary repeat requests.

Importance of Cache Control​

  • Reduces Latency: Cached responses are served faster.
  • Minimizes Server Load: Fewer requests hit the backend.
  • Saves Bandwidth: Avoids transferring the same data repeatedly.
  • Consistency vs. Freshness: Balances performance with ensuring up-to-date information.

Key Cache-Control Header Directives​

The Cache-Control header is the primary way to control caching behavior in REST APIs.

DirectiveMeaning
publicResponse can be cached by any cache (browser, proxy, CDN).
privateResponse is intended for a single user (e.g., personalized content).
no-cacheForces revalidation before using cached data.
no-storePrevents any caching at all.
max-age=<seconds>Specifies how long (in seconds) the response can be cached.
must-revalidateForces caches to obey expiration times strictly.

How Cacheability Is Controlled​

Cacheability in REST APIs is mainly controlled using HTTP cache headers:

HeaderPurpose
Cache-ControlMain directive for caching policies
ETagEntity Tag for validating cached responses
Last-ModifiedTimestamp for resource freshness
ExpiresDate-time when response becomes stale

Example of cache control​

Static Resource​

Header Example

Cache-Control: public, max-age=31536000

Explanation:

  • Cached for 1 year.
  • Publicly cacheable by CDNs and browsers.

API Response​

Request

GET /products

Response Header

Cache-Control: public, max-age=60

Explanation:

  • Cached for 60 seconds.
  • Public caches and browsers can store the response for a short duration.

Sensitive/Dynamic Data​

Request

GET /user/profile

Response Header

Cache-Control: private, no-store

Explanation:

  • Private: Only for the specific user’s browser cache.
  • No-store: Avoid caching altogether to prevent sensitive information from being stored.

Combining Directives​

Header Example:

Cache-Control: private, max-age=0, no-cache, must-revalidate

Behavior:

  • Private: Only for that user.
  • max-age=0: Response expires immediately.
  • no-cache: Client must check with the server before using cached data.
  • must-revalidate: Cache must not serve stale content.

How Cache-Control Fits into REST API Workflow​

  • Server Sets the Cache-Control Header: During the response.
  • Client or Intermediary Respects It: Determines whether to use cached content or request new data.
  • Stale Content Handling: APIs can use other headers like ETag and Last-Modified for conditional requests.

Implement Cache Control​

app.get("/products", (req, res) => {
  res.set("Cache-Control", "public, max-age=60");
  res.json({
    products: [
      /* product data */
    ],
  });
});
  • ETag: Entity tag used to check if the cached version is still valid.
  • Last-Modified: Timestamp indicating when the resource was last updated.
  • Expires: Legacy header; often replaced by Cache-Control: max-age.